GraphQL Provider

GraphQL query implementation for UTCP

The GraphQL provider enables UTCP to interact with GraphQL APIs, allowing for precise data fetching and operations with a flexible query language. GraphQL's type system and query capabilities make it ideal for complex data requirements with minimal network overhead.

Configuration

GraphQL providers are configured using the following JSON structure:

{
  "name": "graphql_api",
  "provider_type": "graphql",
  "url": "https://api.example.com/graphql",
  "operation_type": "query",
  "operation_name": "GetUserData",
  "timeout": 30000,
  "auth": {
    "auth_type": "api_key",
    "api_key": "YOUR_API_KEY",
    "var_name": "Authorization"
  },
  "headers": {
    "User-Agent": "UTCP Client",
    "Content-Type": "application/json"
  },
  "header_fields": ["client_version", "trace_id"]
}

Configuration Fields

Field	Required	Description
`name`	Yes	Unique identifier for the provider
`provider_type`	Yes	Must be set to `"graphql"`
`url`	Yes	Full URL to the GraphQL endpoint
`operation_type`	No	Type of GraphQL operation: `"query"`, `"mutation"`, or `"subscription"` (default: `"query"`)
`operation_name`	No	Name of the GraphQL operation (optional, but recommended)
`timeout`	No	Request timeout in milliseconds (default: `30000`)
`auth`	No	Authentication configuration (if required)
`headers`	No	Additional HTTP headers to include in the request
`header_fields`	No	List of input fields to be sent as request headers

Authentication Options

GraphQL providers support the same authentication methods as HTTP providers:

API Key Authentication

{
  "auth": {
    "auth_type": "api_key",
    "api_key": "YOUR_API_KEY",
    "var_name": "Authorization"
  }
}

Bearer Token Authentication

{
  "auth": {
    "auth_type": "bearer",
    "token": "YOUR_BEARER_TOKEN"
  }
}

Basic Authentication

{
  "auth": {
    "auth_type": "basic",
    "username": "your_username",
    "password": "your_password"
  }
}

Operation Types

GraphQL supports three types of operations:

Query

Read-only operations to fetch data. Most common operation type.

Mutation

Operations that modify data on the server (create, update, delete).

Subscription

Real-time operations that listen for data changes over WebSocket.

Tool Discovery

For GraphQL providers, tool discovery can be done in two ways:

1. UTCP Discovery Endpoint

The tool discovery endpoint should be accessible at /utcp on the same domain:

https://api.example.com/utcp

2. GraphQL Schema Introspection

Tools can be discovered through introspection of the GraphQL schema using the standard introspection query:

query IntrospectionQuery {
  __schema {
    queryType { name }
    mutationType { name }
    subscriptionType { name }
    types {
      ...FullType
    }
  }
}

Examples

User Data Query

{
  "name": "user_api",
  "provider_type": "graphql",
  "url": "https://api.example.com/graphql",
  "operation_type": "query",
  "operation_name": "GetUser",
  "auth": {
    "auth_type": "bearer",
    "token": "YOUR_JWT_TOKEN"
  }
}

Product Creation Mutation

{
  "name": "product_api",
  "provider_type": "graphql",
  "url": "https://api.example.com/graphql",
  "operation_type": "mutation",
  "operation_name": "CreateProduct",
  "timeout": 60000,
  "auth": {
    "auth_type": "api_key",
    "api_key": "YOUR_API_KEY",
    "var_name": "X-API-Key"
  }
}

Real-time Updates Subscription

{
  "name": "notifications_api",
  "provider_type": "graphql",
  "url": "wss://api.example.com/graphql",
  "operation_type": "subscription",
  "operation_name": "NotificationUpdates",
  "auth": {
    "auth_type": "bearer",
    "token": "YOUR_SUBSCRIPTION_TOKEN"
  }
}

Sample GraphQL Operations

Query Example

query GetUser($id: ID!) {
  user(id: $id) {
    name
    email
    role
    profile {
      avatar
      bio
    }
  }
}

Mutation Example

mutation CreateProduct($input: ProductInput!) {
  createProduct(input: $input) {
    id
    name
    price
    success
    errors {
      field
      message
    }
  }
}

Subscription Example

subscription OnCommentAdded($postId: ID!) {
  commentAdded(postId: $postId) {
    id
    content
    author {
      name
    }
    createdAt
  }
}

Best Practices

Query Optimization

• Use precise field selection to reduce payload size
• Implement query depth limiting to prevent abuse
• Use fragments for reusable field selections

Error Handling

• Handle GraphQL-specific errors in responses
• Implement proper validation for input variables
• Use operation names for better debugging

Performance

• Consider query batching for multiple operations
• Implement caching strategies for frequently accessed data
• Use persisted queries for better performance

Security

• Implement rate limiting and query complexity analysis
• Validate and sanitize all input variables
• Use proper authentication for sensitive operations